Overview

The Driver Settlements API lets a partner financial institution act as a cash counter for Presto drivers, in both directions:

Operation	Direction of money	What it settles
Cash In	Driver → Presto	The driver's outstanding debt — cash the driver has collected on Presto's behalf (COD collections, wallet top-ups performed for customers) and still owes.
Cash Out	Presto → Driver	The driver's available earnings — delivery fees and incentives Presto owes the driver.

Both operations use the same two-step init → confirm pattern as Wallet Top-Up, so an institution that already integrates wallet top-up can reuse its transport, authentication and reconciliation code.

Balance model

Every Presto driver carries two independent balances. They are never netted automatically:

• outstanding_debt — what the driver owes Presto. Cash In reduces it. It can never go below zero.
• available_earnings — what Presto owes the driver. Cash Out reduces it. It can never go below zero.

A driver may hold both balances at the same time. If the driver wants to settle debt out of earnings, that is a Presto-side operation and is not exposed through this API.

Process flow

Integration steps

1. Identify the Driver

Call the lookup endpoint to resolve the driver and read both balances before offering any operation.

2. Initialize

Call Cash In init or Cash Out init to reserve the amount and obtain a transaction reference.

3. Verify with the Driver

Show the returned driver name and amount. For Cash Out, collect the OTP delivered to the Presto driver app.

4. Confirm

Call Cash In confirm or Cash Out confirm. Move the physical cash only after a 200 OK.

5. Reconcile

Use the transaction status endpoint for end-of-day reconciliation and for any request whose response you did not receive.

6. Handle Expiry

Unconfirmed transactions expire after 15 minutes and are voided automatically. No cancellation call is required.

Cash handling rules

Cash movement is bound to the confirm response

• For Cash In, accept the driver's cash only after confirm returns 200 OK. A 5xx or a timeout means the outcome is unknown — resolve it with transaction status before taking or returning money.
• For Cash Out, hand over cash only after confirm returns 200 OK. Presto has already debited the driver's earnings at that point.
• Never retry confirm blindly after a timeout. Retrying is safe only with the same transaction_reference and the same Idempotency-Key (see below).

Idempotency

Every init and confirm request requires an Idempotency-Key header (a UUID v4 you generate per logical operation).

Situation	Behaviour
Same key, same payload, replayed	The original response is returned with an Idempotent-Replayed: true header. No second settlement or payout occurs.
Same key, different payload	409 Conflict — Idempotency key already used with a different payload.
Same key while the first request is still running	409 Conflict — A request with this Idempotency-Key is already in progress. Wait, then retry with the same key.
Header missing or not a valid UUID v4	422 Unprocessable Content — The Idempotency-Key header must be a valid UUID v4. The request is not processed.

Keys are scoped to the endpoint, so you may reuse one key for the init and the confirm of the same operation. Only successful (2xx) responses are stored and replayed: a request that failed changed nothing, so retrying it with the same key runs it again (for example, a second OTP attempt).

Keys are retained for 24 hours.

Your own reference

Both init calls require an institution_reference — your identifier for the operation in your own system (a teller transaction number, a voucher number, whatever you reconcile against).

Rule	Behaviour
Uniqueness	Must be unique within your institution. Reusing one returns 409 Conflict together with the transaction_reference it already belongs to.
Echoed everywhere	Returned on init, on confirm, and on every transaction status response, so both sides can match records without a manual lookup.
Reverse lookup	You can query a transaction by your own reference: GET /drivers/transaction?institution_reference=.... Useful when you hold your reference but not ours.
Format	1–64 characters: letters, digits, hyphens and underscores.

Print both references

Put your institution_reference and Presto's transaction_reference on the driver's receipt. Either side can then open a dispute from whichever number they hold.

Amounts and currency

Rule	Value
Decimal precision	Up to 3 decimal places
Currency	Determined by the driver's operating country and returned on every response. Institutions must send the same code the lookup returned.
Minimum amount	1.000
Partial settlement	Allowed for Cash In — the driver may pay any amount up to outstanding_debt.
Partial payout	Allowed for Cash Out — the driver may withdraw any amount up to available_earnings.
Over-settlement / over-payout	Rejected with 422. Presto does not create credit balances through this API.

Currency in the examples

Examples on the following pages use LYD, matching the rest of this documentation. The API does not hard-code a currency: always echo back the currency returned by driver lookup rather than assuming one.

Error handling

Common integration challenges

Challenge	Resolution
Driver not found	Confirm the identifier type and format match what the driver is registered with in Presto.
Amount exceeds balance	Re-run driver lookup — balances change as the driver works.
Expired transaction	Re-initialize. References expire 15 minutes after init.
Unknown outcome after a timeout	Query transaction status before any cash moves. Never assume failure.
Driver suspended or blocked	403 on Cash Out. The driver must be reactivated by Presto operations before being paid. A suspended driver can still settle debt (Cash In).

Open points to confirm

To agree with IZI Zitouna before implementation

• Whether IZI calls Presto (the model documented here) or Presto calls IZI to push payouts
• Whether Cash Out requires the OTP step described here, or IZI branch-level authorization is sufficient
• Settlement currency and FX handling if IZI settles in TND while driver balances are held in LYD
• Daily per-driver and per-branch limits for Cash Out
• Whether a reconciliation file / statement endpoint is needed in addition to per-transaction status
• Refund or reversal process for a Cash In credited to the wrong driver

Support

For questions on this specification, contact support@presto.app and include the transaction references, payloads (with sensitive data redacted) and timestamps involved.